using lucere.exception;

namespace lucere.service.search.collect
{
	///<summary>
	/// The <see cref="ITimeLimitingCollector"/> is used to timeout search requests that
	/// take longer than the maximum allowed search time limit. After this time is
	/// exceeded, the search thread is stopped by throwing a
	/// <see cref="TimeExceededException"/>.
	///</summary>
	public interface ITimeLimitingCollector:ICollector
	{
		///<summary>
		/// Set the timer resolution.
		/// The default timer resolution is 20 milliseconds. 
		/// This means that a search required to take no longer than 
		/// 800 milliseconds may be stopped after 780 to 820 milliseconds.
		/// <br/>Note that: 
		/// <ul>
		/// <li>Finer (smaller) resolution is more accurate but less efficient.</li>
		/// <li>Setting resolution to less than 5 milliseconds will be silently modified to 5 milliseconds.</li>
		/// <li>Setting resolution smaller than current resolution might take effect only after current 
		/// resolution. (Assume current resolution of 20 milliseconds is modified to 5 milliseconds, 
		/// then it can take up to 20 milliseconds for the change to have effect.</li>
		/// </ul>      
		///</summary>
		int Resolution { get; set; }

		///<summary>
		/// Checks if this time limited collector is greedy in collecting the last hit.
		/// A non greedy collector, upon a timeout, would throw a <see cref="TimeExceededException"/> 
		/// without allowing the wrapped collector to collect current doc. A greedy one would 
		/// first allow the wrapped hit collector to collect current doc and only then 
		/// throw a <see cref="TimeExceededException"/>.
		/// <see cref="Greedy"/>
		///</summary>
		bool Greedy { get; set; }
	}
}